AN-26101301 子设备控制最佳实践
通过 RS-485、M-Bus 或串口采集器控制子设备时，只有本次有效设备反馈满足对应操作的成功条件，才结束等待。平台接收请求、下行入队、无线 ACK、设备写应答和真实运行状态是不同阶段，必须分别判断。
本文说明参数读取、参数设置和动作控制的完整闭环，适用于接入开发、应用开发与现场验收。设备支持的参数、地址、类型、范围和动作，以实际协议、已绑定 RPC 与接收物模型为准。helper 部分依据 2026-10-13 的 tkl-opt 1.01.43 / V3 合同；目标宿主能力需单独核实，本文不代表任一租户已部署或通过真机验收。
1. 先定义“成功”代表什么
| 操作或反馈 | 可以得出的结论 | 下一步 |
|---|---|---|
| 平台受理 / 下行入队 | 平台已接收请求 | 等待目标设备反馈 |
| LoRaWAN ACK | 无线链路取得对应确认 | 继续判断子设备协议与业务结果 |
| GET 参数读回 | 取得本次实际参数值 | 保存值、类型、单位和观测时间；不能写成“设置成功” |
| SET 参数读回 | 本次有效读数与目标一致 | 确认参数，更新模型并通知消费者 |
| 协议明确足以证明参数写入的应答 | 参数写入得到协议级确认 | 按协议标明确认依据；不能泛化为机械动作完成 |
| 开关机/继电器写应答 | 设备接受了写命令 | 显示“已应答，等待实际状态反馈” |
| 本次命令之后的有效运行状态 | 设备回报状态达到目标 | 结束应用等待；机械效果按业务需要另验 |
| 到期仍缺少有效反馈 | 结果未确认 | 有界只读回查或现场检查，不重复原写命令 |
“失败”应有协议异常、参数校验或保护条件等明确依据。没有回复只能说明证据不足，不能据此断言设备没有执行。清零、脉冲等无可读持续状态的动作，只报告协议支持的结果/阶段，不制造虚假的参数或运行值。
2. 操作前核对对象与配置
在 运维管理 → 设备管理 → 目标设备 → 详情 → RPC 查看实际挂载或继承的操作。先核对以下内容，再提交一次命令：
| 核对项 | 要求 |
|---|---|
| 身份与路由 | 组织、目标 EUI、父采集器、接口、从机地址/控制通道及接收模型一致，不能只按名称选择 |
| 平台子设备 | 物理下行经过实际父设备 device.parent；业务参数和状态保存到实际目标子设备，不能把所有属性动作改给父设备 |
| RPC 与模型 | 使用真实 Method/标识和绑定，明确 SET、GET、Action 与接收分支的对应关系 |
| 参数定义 | SET、GET、解析模型的地址、类型、字节宽度、倍率、单位与合法范围一致 |
| 当前值 | 展示真实值及其原更新时间；没有有效值时显示“暂未收到数据”，不把表单默认值当设备现值 |
| 安全与权限 | 保留参数校验、权限及真实设备保护联锁；用户取消不发送 |
参数表单可以优先读取对应模型的有效遥测，缺失再回退兼容属性或已批准默认值。这是应用读取策略，不能用缓存回填值参与本次事务确认，也不能自行新增平台不支持的 default_from 枚举。
采集器在线不代表子设备通信正常。通信异常时提示“指令可能无法送达”，缺失或过期时提示“通信状态未知”；仅通信风险不应成为禁用已授权控制的理由。
3. 建立可追踪的反馈链
用户提交 SET / GET / Action
→ 校验目标、参数、权限和真实保护条件
→ 发送 RPC，记录本次事务与确认期限
→ 父采集器转发，子设备返回协议反馈
→ 接收物模型校验对象、报文、事务和实际字段
→ 参数确认 / 已应答待状态 / 结果未确认 / 明确失败
→ 更新已声明的参数或遥测字段
→ MQTT 通知，页面按同一操作更新结果记录 RPC、接收模型、字段、确认依据和消息责任方。helper 内部事务、日志、业务模型和页面等待各有职责，不能只看到某一处 SUCCESS 就宣告整条链路完成。
4. 回读判断逻辑
按以下顺序处理每次反馈。任何条件未满足，都不能将这条反馈用于确认当前操作。
- 对象和模型正确：核对子设备身份、父链路、从机地址、通道和接收模型。其他设备同名字段或同值回包不参与比较。
- 协议有效：校验端口、长度、地址、功能码、寄存器/数量/值和 CRC，拒绝异常帧及错误类型。51 端口只标识透传通道，不保证回包与下行完全相同。
- 反馈归属本次操作：核对当前事务和协议支持的请求标识，排除旧包、重复包和已被新事务取代的反馈。观测时间应来自实际反馈链，不能用页面接收时间刷新旧样本后伪装成新状态。
- 字段确实来自本次反馈：缺失字段保持缺失，不能拼接缓存或请求目标补齐。整数、布尔、字符串、倍率及单位按实际模型严格判断。
- 采用正确成功条件：GET 保存真实读数；SET 判断所有必要参数是否确认；Action 区分写入应答与实际状态。开关机必须等待本次命令之后的有效状态与目标一致。
- 发布对应业务结果：更新正确模型并通知消费者，保留实际值、确认依据和观测时间。对同一反馈去重，后续真实状态变化继续正常发布。
协议没有请求号时，内部事务 ID 和平台收包时间无法严格区分两次相同命令的迟到同值回包。应顺序执行同一控制通道的操作、处理在途命令，并在协议支持时重新读取；交付时注明剩余关联限制，不能声称完全消除歧义。
4.1 参数设置示例
假设设备协议允许把某参数从 20 改为 25。这些数值仅用于解释逻辑，不是设备推荐配置。
| 收到的内容 | 判断 |
|---|---|
| 平台接收成功 | 等待设备反馈 |
| 缓存中已经是 25 | 不能确认本次设置；相同值新设置也要本次反馈 |
| 其他从机回报 25 | 拒绝用于当前事务 |
| 当前从机回包 CRC 错误 | 拒绝用于成功判断 |
| 当前事务有效读回 25 | 确认参数并发布模型结果 |
| 目标同时包含上限 30、下限 20，本帧只回上限 30 | 保持未确认；不能从缓存补上下限 |
| 到期后只读查询得到 25，但协议不能关联原写入 | 报告“回查当前值为 25”；不据此证明原命令执行过程或机械效果 |
4.2 开关机示例
以实际模型声明为数字的 power_switch 为例，目标 1 表示开机，0 表示关机：
| 阶段 | 页面与模型处理 |
|---|---|
提交开机目标 1 | 保留原实际状态，显示“平台已接收，等待设备反馈” |
| 收到有效 Modbus 写应答 | 显示“已应答，等待实际状态反馈”；不把目标 1 写成实际 power_switch |
收到当前设备、当前模型的新状态 0 | 展示真实状态，继续等待目标或到期处理 |
收到其他模型的 1、字符串 "1" 或旧样本 1 | 不能结束等待 |
收到本次命令之后的有效数字状态 1 | 显示“设备已回报开机”，结束该次等待 |
若模型本来使用布尔值或其他枚举，应按原合同判断，不为套用示例改变类型。事务仍显示 PENDING 时，业务层已验证的新鲜状态也可作为实际状态确认依据；同样，helper 的写应答 SUCCESS 不能替代真实状态。需要证明电机运行、阀门到位等效果时，还需对应传感器或现场证据。
5. tklHelper V3 的接入要点
库版本 1.01.043、数字事务版本 3、传输报文 dnMsg.version 是不同编号。旧调用默认仍为 V2，迁移时发送 RPC 与接收物模型必须配套选择 V3，不能全局修改默认版本。
| 位置 | 实现要求 |
|---|---|
| 发送 RPC | Utils.makeParaSetMSG({ version: 3, ... }) 只接收实际可由反馈复现的比较参数，沿用原协议编码和通道 |
| 214 接收 | 使用实际 paraDef 解析本帧参数，调用 Utils.paraCheck(rpcName, device, parsedParams, { version: 3 }) |
| 51 接收 | 先按实际协议过滤有效目标帧，再以 { device, msg } 配合完整 checkInfo 检查；单帧 Modbus 校验见下文 |
| GET | 无目标值时只构造读取队列，接收真实读数，不伪造写入成功事务 |
| 参数回填 | 使用已声明且类型一致的 telemetryFields 白名单或显式映射；旧表单需要时可双写 shared_attrs |
| 动作写应答 | 完整有效的 checkInfo 中设 telemetry_data: null，不经 shared/server 映射伪造实际状态 |
| 返回结果 | 按组保留所有 process/telemetry/shared/server 补丁和 actions，处理同名冲突，不整组覆盖或重发缓存旧遥测 |
标准单帧 Modbus FC05/06 写应答应比较完整 8 字节；FC10 应答由请求前 6 字节和重新计算的应答 CRC 构成。多帧及其他协议要单独定义解析。tkl-opt 适配器使用的 expected_hex 是脚本层校验约定，helper 不自动解释它。
V3 完整事务保存到 process_data.__para_set__<rpcName>，透传共用 process_data.__para_set__transParent。同一槽位不能并发独立命令；过程数据不是原子锁、并发隔离或强持久化账本。
生产适配还应读取 V2/V3 及实际旧别名的最新记录，按 rpcInfo.ms 选择，同时间优先 V3；最新记录已终态就不复活旧事务。Class A 重试使用 _tkl_v3_retry={version,rpc,ms,transactionId}，在 RPC 最外层、任何下发或复位之前检查身份和 RETRY_READY；无标记用户调用建立新事务。升级前无标记的在途回调需单独处理。
上述兼容选择、重试入口保护和完整 Modbus 检查属于配套脚本逻辑，单加 version: 3 不会自动获得这些能力。详细 API、映射和边界见 tklHelper 子设备回读接入。
6. 响应时间、有限重试与超时回查
一般 RS-485＋LoRaWAN 单次响应以 10 秒（10000 ms） 为常用工程起点，覆盖一次下行、串口处理及反馈链路，再按设备协议、慢动作、空口排队与实测调整。这不是 LoRaWAN 标准保证，也不是统一的串口驱动 timeout。
| 场景 | 时间与重试策略 |
|---|---|
| Class A | 总窗口包含下一次可用上行接收机会、单次响应及实际反馈上传等待/裕量；提交后 10 秒未回包不能直接判失败 |
| Class C 参数写入，已允许重试 | 重发间隔通常不短于单次响应预算；总窗口至少覆盖最后一包计划时间加一次响应及排队裕量 |
| 非幂等动作 | 默认 maxRetries: 0；只有协议依据和明确授权支持时才启用有限重试 |
| 超时 | 显示“结果未确认”；协议支持且操作已授权时执行一次有界只读查询，仍无结果保留未知 |
| 日志失败/页面重开 | 不因此重发写命令，不额外启动一轮控制 |
例如 Class C 配置 timeout: 10000、retryIntervalMs: 10000、maxRetries: 2，计划最多 3 包，总窗口默认 30000 ms。额外排队或慢反馈可用 echoTimeoutMs 显式放宽。应注明计时从提交、入队还是实际发送开始；helper 的 rpcInfo.ms 从事务创建起计，不证明实际发射时间。不要为套用 Class C 示例擅自切换设备 Class。
Class C 匹配后通过 mt_action/downBufferClear 清理设备队列，不是精确撤销某条事务，已经发出的包也不能撤回。不匹配不会提前清队列；到期要后续调用检查函数才写入 EXPIRED，不会自动定时扫描或清除既有队列。页面显示到期与设备队列取消是两件事。安排只读回查前，应核实在途写命令与实际队列状态，避免把回查结果解释为随后绝不会再发生变化。
7. 参数模型与 MQTT 必须闭环
确认后的真实参数进入目标模型的实时数据或参数数据，优先使用 telemetry_data。旧表单兼容回填 shared_attrs 时，也要核实模型展示与消息路径。不能把“参数不是遥测”作为不推送结果的理由。
每次有效反馈由单一责任方沿平台已有模型/属性链发送可关联的 MQTT 业务通知，重复回包去重；正常、明确失败和未确认也应通过已声明的业务结果字段让操作方获知。实际 topic、payload、字段及权限按目标平台核实，不假设存在通用的结果字段或新 API。
使用属性通知时，检查最小 forward_fields 白名单及实际消息。forward: true 不绕过白名单，forward: false 不发送本次属性通知，配置白名单本身不会主动发消息。不要为了补结果再并发发一份 customMqtt；业务去重不等于 MQTT 网络层 exactly-once。
页面应能关联设备、模型/字段、事务或请求、反馈阶段与观测时间，无需手动刷新即可获知结果。process_data、事务成功、日志、rpcHook 或队列清理都不能替代该消息证据。详见设备属性转发与过程数据。
8. 交付验收与排查
至少执行以下用例，并分别记录本地联测、平台脚本与绑定回读、真实设备反馈、MQTT 实际消息、页面等待结束及物理效果的证据。脚本测试通过不能替代后几项。
| 用例 | 预期 |
|---|---|
| 正常参数设置及 GET | 本次反馈有效；实际值、类型和单位正确；GET 不显示设置成功 |
| 目标与缓存同值、部分回包 | 缓存不能确认本次操作，也不能补齐缺失字段 |
| 错设备/从机/模型、错误 CRC/功能码/寄存器 | 不污染目标模型，不误判成功 |
| 重复回包、迟到旧包、被新事务取代的反馈 | 不重复发布同一业务结果、不复活旧事务；协议关联局限明确记录 |
| 写 ACK 正常但状态不符 | 保留已应答待实际反馈，不伪造 power_switch 或观测时间 |
| Class A 尚未获得下行机会 | 不机械按提交后 10 秒判失败；过时重试在产生副作用前被拒绝 |
| Class C 最后一包及慢反馈 | 总窗口覆盖响应预算；核对匹配取消、不匹配继续及清队列影响范围 |
| 超时与回查仍无结果 | 保留未知，不重复原动作；到期显示不冒充队列已取消 |
| 模型输出和 MQTT | 保留其他数据与 actions；每次有效反馈有可识别通知，页面无需手动刷新 |
| 日志失败 | 业务只执行一次；可查询日志覆盖正常、异常、无变化与异步结果 |
持久化日志需关联设备、RPC、事务 ID、时间、来源与状态变化。Utils.withExecutionLog 只是宿主 logger 适配，log_storage: true 和过程数据都不证明日志已落库。宿主未提供 logger 或缺查询证据时，保留“未验”结论。
常见排查顺序：没有有效回包先查路由与协议；有回包但未确认查事务、字段与时间；参数已确认但页面不更新查模型输出、转发白名单、消息和订阅；写应答后运行状态未到查实际状态读取与设备保护条件。不要用增加重发次数掩盖反馈缺口。
9. 相关章节与依据
工程依据为 tkl-opt 的 capabilities/rules/tklhelper-v3-subdevice-control.md、capabilities/rules/subdevice-parameter-feedback.md，以及 docs/references/ 下的 subdevice-parameter-action-guide.md、tklhelper-parameter-versions.md 和 tklhelper-rpc-model-usage.md。协议示例与时间预算应在目标设备上验证后采用。